pg_copyplot
===========

Contents
--------

1. Primary Use Cases
2. Basic Usage
3. RoadMap
4. License and Copyright

1 Primary Use Cases
====================

Machines are good in processing numbers, even in large scale compared to humans.
That may have its foundation in machines design.

Humans however are good in recognizing and interpreting pictures.
As we aren't good in getting a grip from raw numbers only, it is a necessety for us to see them manifestating in plots.
This helps us to interpret and analyze relationships measured with numbers using statistical methods.

When dealing with Postgre SQL databases, there is no simple way of preparing stored data into statistical plots within the psql shell.
However, such an ability would enable the user to quickly form a mental model of the characteristics of the data.
Exploiting the COPY command of Postgre SQL, pg_copyplot tries to facilitate the previously depicted usage scenario.


2 Basic Usage
==============

pg_copyplot can be used as follows:

Step 1: Starting the Server

Run "start_plotserver.sh".

Step 2: Plot from psql via the Postgre SQLs COPY command:

  COPY table/(select query) TO PROGRAM '/path/to/python3 /path/to/pg_copyplot.py -x 1 -y 3' WITH (FORMAT CSV, DELIMITER ',');

E.g. having a table t_abfall like this:
Tabelle »public.t_abfall«
          Spalte          |       Typ        | Attribute 
--------------------------+------------------+-----------
 jahr                     | integer          | 
 bundesland               | text             | 
 anzahlabfallerzeuger     | integer          | 
 abfallmengen1kt          | double precision | 
 abfallmengen_primerz_1kt | double precision | 


  COPY (select * from t_abfall where bundesland = 'Baden-Württemberg') TO PROGRAM '/usr/bin/python3 /home/talthybios/Software-Projekte/pg_copyplot/pg_copyplot.py -x 1 -y 3' WITH (FORMAT CSV, DELIMITER ',');

3 RoadMap
==========

The following ideas for improving pg_copyplot lie around:
- automatic determination of column delimiter characters (e.g. by looking at frequency distribution of some popular choices)
- enable the user to select data frames to plot via column names (in case of header available)
- annotate the axes of the plot with column names (in case of header available)
- include more than one data series in the plot by segregation of data series by factor variable, specified either by index or name

4 License and Copyright
========================

    Copyright (C) 2017 Markus Zeindl

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.
